<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <!-- vi:set sw=2: -->
  <!--
  Copyright (C) 1996-2002  Brian Paul and Ben Bederson
  Copyright (C) 2005-2009  Greg Couch
  See the LICENSE file for copyright details.
  -->

  <head>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
    <title>Using the Togl Widget</title>
  </head>

  <body>
    <script type="text/javascript" src="header.js"></script>
    <script type="text/javascript">
      NavigationBar();
    </script>

    <h1 align="center">Using the Togl Widget</h1>

    <h2>Contents</h2>
    <ul>
      <li><a href="#using">Using Togl With Your Application</a>
      <li><a href="#examples">Examples</a>
      <li><a href="tclapi.html">Tcl API</a>
      <li><a href="capi.html">C API</a>
    </ul>

    <hr>

    <h2><a name="using">Using Togl With Your Application</a></h2>

    <p>
    First, double check that you have all of the
    <a href="download.html#prereq">prerequisites</a>
    and that you have
    <a href="download.html#building">compiled and installed</a> Togl.
    <p>
    Then, Togl acts like any other extension package &mdash;
    to load it, you use the Tcl <code>package</code> command:
    <blockquote>
      <code>package require Togl 2.0</code>
    </blockquote>
    After that, you can create a Togl widget just like any other Tk widget.

    <h2><a name="examples">Examples</a></h2>

    <p>
    There are eight working examples:

    <blockquote>
      <table border="0">
	<tr>
	  <td>double.tcl</td>
	  <td>&mdash; compares single vs double buffering with two Togl widgets</td>
	</tr>
	<tr>
	  <td>texture.tcl</td>
	  <td>&mdash; lets you play with texture mapping options</td>
	</tr>
	<tr>
	  <td>index.tcl</td>
	  <td>&mdash; example of using color index mode</td>
	</tr>
	<tr>
	  <td>overlay.tcl</td>
	  <td>&mdash; example of using overlay planes (requires overlay hardware)</td>
	</tr>
	<tr>
	  <td>stereo.tcl</td>
	  <td>&mdash; stereo example</td>
	</tr>
	<tr>
	  <td>gears.tcl</td>
	  <td>&mdash; spinning gears example</td>
	</tr>
	<tr>
	  <td>multisample.tcl</td>
	  <td>&mdash; multisampling example</td>
	</tr>
	<tr>
	  <td>pbuffer.tcl</td>
	  <td>&mdash; pbuffer (off-screen rendering) example</td>
	</tr>
      </table>
    </blockquote>

    <p>
    Each example consists of two files: a Tcl script for the user interface,
    and a Tcl C package that does the OpenGL drawing.
    To compile the examples, type <code>make examples</code>
    in the Togl source directory.
    The C packages are compiled into shared libraries
    that are loaded into the Tcl interpreter as Tcl/Tk-extensions.
    The examples are started by running the corresponding Tcl script:
    just type <code>./double.tcl</code>
    (or <code>./texture.tcl</code> <i>etc.</i>)
    or run under one of the Tcl interpreters, <i>i.e.</i>,
    <code>tclsh</code> or <code>wish</code>.
    For example:
    <blockquote>
      <code>tclsh84 double.tcl</code>
    </blockquote>

    <p>
    Other examples that use Tcl for OpenGL drawing can be found in the
    <a href="http://tcl3d.org/html/demos.html">Tcl3D demos</a>.

    <h3><a name="callbacks">Togl callbacks</a></h3>
    <p>
    All of the examples have similar structure.
    First they create the user interface with one or more Togl widgets.
    Each Togl widget is configured with the desired pixel format
    and several callback commands (not all are needed):
    <table>
      <tr>
	<td><code>-createcommand</code></td>
	<td>
	  Called when Togl widget is mapped &mdash;
	  when it is safe to initialize the OpenGL context.
	</td>
      </tr>
      <tr>
	<td><code>-reshapecommand</code></td>
	<td>
	  Called when the Togl widget is resized &mdash;
	  when the OpenGL context's viewport needs to be changed.
	</td>
      </tr>
      <tr>
	<td><code>-displaycommand</code></td>
	<td>
	  Called when the contents of the Togl widget needs to be redrawn.
	  Redraws are normally delayed to be when the Tcl event loop is idle
	  (see the togl widget's <code>postredisplay</code> command),
	  or as the result of an explicit call to the togl's widgets
	  <code>render</code> command.
	</td>
      </tr>
      <tr>
	<td><code>-destroycommand</code></td>
	<td>
	  Called when the Togl widget is destroyed.
	  While OpenGL frees display lists and other resources,
	  sometimes there's some associated state that is no longer needed.
	</td>
      </tr>
      <tr>
	<td><code>-timercommand</code></td>
	<td>
	  Called every <i>n</i> milliseconds
	  as given by the <code>-time</code> option.
	</td>
      </tr>
      <tr>
	<td><code>-overlaydisplaycommand</code></td>
	<td>
	  Called when the overlay planes needs to be redrawn.
	  The overlay planes are created and reshaped
	  at the same time as the main OpenGL context.
	</td>
      </tr>
    </table>

    Typically, only <code>-createcommand</code>, <code>-reshapecommand</code>
    and <code>-displaycommand</code> are used.

    <hr>
    <a href="http://sourceforge.net/projects/togl">
      <img src="http://sflogo.sourceforge.net/sflogo.php?group_id=519&amp;type=13" width="120" height="30" border="0" alt="Get Togl at SourceForge.net. Fast, secure and Free Open Source software downloads">
    </a>
    <a href="http://validator.w3.org/check?uri=referer">
      <img src="http://www.w3.org/Icons/valid-html401-blue"
      alt="Valid HTML 4.01 Transitional" height="31" width="88" border="0">
    </a>
  </body>
</html>
